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What are Derived Quantities? 


Navigation and Ancillary Information Facility 


¢ Derived quantities, what we often call “observation 
geometry,” are produced using data from SPICE kernels 
and Toolkit software. 


— These are the primary reason that SPICE exists! 


¢ The SPICE Toolkit contains many routines that assist with 
the computations of derived quantities. 


— Some are fairly low level, some are quite high level. 
la mole are being added as time permits. 
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SPICE Kernels Your Program Derived Quantities 


¢ Examples follow on the next several pages. 


Derived Quantities 


High-level Geometric Computations 
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¢ Geometric Parameter 
— Determine a geometric quantity or condition at a specified time. 


¢ Geometry Finder (GF) 


— Find times, or time spans, when a specified “geometric event” 
occurs, or when a specified “geometric condition” exists. 


» This is such a large topic that a separate tutorial 
(“geometry_finder”’) has been written for it. 
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NAIE> Examples of Geometric Parameters - 1 
Navigation and Ancillary Information Facility 


¢ [Illumination angles (phase, incidence, emission) 
— ILLUMF, ILLUMG, ILUMIN* 
¢ Sub-solar point 
— SUBSLR* 
¢ Sub-observer point 
— SUBPNT* 
¢ Surface intercept point 
— SINCPT*, DSKXV, DSKXSI 
¢ Tangent point 
— TANGPT 
¢ Phase angle between body centers 
— PHASEQ 
¢ Angular separation between two objects 
— TRGSEP 
* These routines supercede the now deprecated 


routines ILLUM, SUBSOL, SUBPT and SRFXPT 
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NAIE> Examples of Geometric Parameters - 2 
Navigation and Ancillary Information Facility 


¢ Longitude of the sun (Ls), an indicator of season 
— LSPCN 
¢ Limb points on an ellipsoid or DSK 
— LIMBPT 
¢ Terminator points on an ellipsoid or DSK 
— TERMPT 
¢ Surface points at specified longitude, latitude coordinates 
— LATSRF 
¢ Outward surface normal on extended object 
— SRFNRM 


¢ Azimuth and elevation of a target as seen from a constant 
position observer 


— AZLCPO 
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NAIE> Examples of Geometric Conditions 
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¢ Ray in field-of-view? 
— FOVRAY 

¢ Ephemeris object within field-of-view? 
— FOVTRG 


¢ Determine occultation condition 
— OCCULT 
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NAIE> Examples of Geometric Searches 
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¢ Find times when: 

— ray is in field-of-view 
» GFRFOV 

— ephemeris object is within field-of-view 
» GFTFOV 

— object is in occultation or transit 
» GFOCLT 

— object is at periapse 
» GFDIST 

— latitude and longitude are in specified ranges 
» GFPOSC 

— solar incidence angle is below a specified limit 
» GFILUM 


¢ For more GF functionality, see the GF tutorial. 
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Geometry Related to Objects 
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Function 


¢ Ellipsoids 


— nearest point 

surface ray intercept 

surface normal 

point on surface 

limb 

slice with a plane 

altitude of ray w.r.t. to ellipsoid 


¢ Planes 


intersect ray and plane 


¢ Ellipses 


project onto a plane 


— find semi-axes of an ellipse 


¢ Lines 


— nearest point on line or segment 
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Routine 


NEARPT, DNEARP 
SURFPT 

SURFNM, EDNMPT 
EDPNT 

EDLIMB 

INELPL 

NPEDLN 


INRYPL 


PJELPL 
SAELGV 


NPLNPT, NPSGPT 


Coordinate Transformation 
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Position Coordinate Transformations 
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Transform state vector 
between two coordinate 
systems 


Latitudinal to/from 
Rectangular 
Planetographic to/from 
Rectangular 


R.A. Dec to/from 
Rectangular 


Geodetic to/from 
Rectangular 
Cylindrical to/from 
Rectangular 


Spherical to/from 
Rectangular 


Azimuth-Elevation to/from 
Rectangular 


Routine 


XFMSTA 


LATREC 
RECLAT 


PGRREC 
RECPGR 
RADREC 
RECRAD 


GEOREC 
RECGEO 


CYLREC 
RECCYL 
SPHREC 
RECS PH 


AZLREC 
RECAZL 


General purpose 
state transformation API 
(except Az-El) 


Single purpose APIs 


Coordinate Transformation 
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Velocity Coordinate Transformations 
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Transform state vector 
between two coordinate 
systems 


Latitudinal to/from 
Rectangular 
Planetographic to/from 
Rectangular 


R.A. Dec to/from 
Rectangular 


Geodetic to/from 
Rectangular 
Cylindrical to/from 
Rectangular 


Spherical to/from 
Rectangular 


Azimuth-Elevation to/from 
Rectangular 


Routine 


XFMSTA 


DRDLAT 
DLATDR 


DRDPGR 
DPGRDR 
DRDLAT 
DLATDR 


DRDGEO 
DGEODR 


DRDCYL 
DCYLDR 
DRDSPH 
DSPHDR 


DRDAZL 
DAZLDR 


General purpose 
state transformation API 
(except Az-El) 


Single purpose APIs 


Examples of Velocity 
Coordinate Transformations 
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This example is for rectangular to spherical 


¢ Using full state vector transformation API 
CALL SPKEZR ( TARG, ET, REF, CORR, OBS, STATE, LT ) 
CALL XFMSTA ( STATE, ‘RECTANGULAR’, ‘SPHERICAL’, ‘ ’, OUTSTATE ) 


¢ Using velocity-only (Jacobian) APIs 


— Transform velocities from rectangular to spherical coordinates using the SPICE 
Jacobian matrix routines. The SPICE calls that implement this computation are: 


CALL SPKEZR ( TARG, ET, REF, CORR, OBS, STATE, LT ) 
CALL DSPHDR ( STATE(1), STATE(2), STATE(3), JACOBI ) 
CALLMXV (JACOBI, STATE(4), SPHVEL ) 


— After these calls, the vector SPHVEL contains the velocity in spherical 
coordinates: specifically, the derivatives 


( d(r)/dt, d (colatitude)/dt, d (longitude) /dt ) 


— Caution: coordinate transformations often have singularities, so derivatives may 
not exist everywhere. 


» Exceptions are described in the headers of the SPICE Jacobian 
matrix routines. 


» SPICE Jacobian matrix routines signal errors if asked to perform 
an invalid computation. 
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Vectors 
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¢ Function ¢ Routine 
— <v,w> — VDOT, 
— vxw — VCROSS, 
— vi||vi| — VHAT, 
— vxw/||vxwll — UCROSS, 
— vtw — VADD, 
— V-w — VSUB, 
— av [+ bw [+ cul] — VSCL, 
— angle betweenvandw - _ VSEP 
— Ilvil - VNORM 
V ae 
-  —= Ww — VPROJ, 
y' 
= V — TWOVEC, 
Ww 
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DVDOT 
DVCRSS 
DVHAT 
DUCRSS 
VADDG 
VSUBG 
[VLCOM, [VLCOM3] | 


VPERP 


FRAME 
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Matrices 
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Selected Matrix-Vector Linear Algebra Routines 


¢ Function 
—-Mxv 
—-MxM 
—Mtxv 
— MtxM 
—-MxMt 
—-vixMxv 
_ Mt 
_ M1 
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Hx Ss 


¢ Routine 


Matrix 

Vector 
Multiplication 
Transpose 


MXV 
MXM 
MTXV 
MTXM 
MXMT 
VIMV 
XPOSE 
INVERT, 


INVSTM 


Euler angles 


Matrix Conversions 
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Function Routines 
es aie — EUL2M, M2EUL 
Transform between Cy Cy Cz 


3x3 rotation matrix 


Be iy Be 0 
——.-.. --=]., , Gy By Gs — EUL2XF, XF2EUL 
y Transform between ee RAV2XF, XF2RAV 
Euler angles and Euler angle rates x By Bz by by by 
or Cy Cy Cy 
rotation matrix and angular velocity 6x6 state transformation 
vector matrix 
nae — RAXISA, AXISAR 
: by ey & ROTATE, ROTMAT 


Rotation axis 
and angle 


(Q,,Q, ,Q2,Q3) 


SPICE Style 
Quaternion 
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Transform between 
3x3 rotation matrix 


A 
Transform between 


re hy © — Q2M, M20 
3x3 rotation matrix 
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Examples of Computing 
NAIE> Derived Quantities 


Navigation and Ancillary Information Facility 


¢ On the next several pages we present examples of 
using some of the “derived quantity” APIs. 


¢ Explore the “Most Used SPICE APIs” document to 
learn more. 
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NAIE> Computing Illumination Angles 
Navigation and Ancillary Information Facility 


¢ Given the direction of an instrument boresight in 
a body-fixed frame, return the illumination angles 
(incidence, phase, emission) at the boresight’s 
surface intercept on an object, with the object’s 
shape modeled by a tri-axial ellipsoid or by DSK 
data. 


incidence 


phase ae 
instrument | emission 


boresight 


direction 


Observer target-observer 
vector 
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NAIE> Computing Illumination Angles 
Navigation and Ancillary Information Facility 


¢ CALL GETFOV to obtain 
boresight direction vector 


neiencs ¢ CALL SINCPT to find 
phase ( eee intersection of boresight 


instrument . P . 
boresight direction vector with surface 


direction 


¢ CALL ILUMIN to determine 
illumination angles 


Observer target-obse 
vector 
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NAIE> Computing Tangent Point 
Navigation and Ancillary Information Facility 


¢ Given the direction of an instrument boresight, 
compute the “tangent point” — the point on the 
boresight ray nearest to the target's surface 
modeled by a tri-axial ellipsoid. 


rei ¢ CALL GETFOV to obtain 
boresight direction vector 
areSene - CALL TANGPT to find the 
direction . 
tangent point on the ray and 
Observer target-obse the point on the surface 


vector 


nearest to it 
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NATE» Computing Ring Plane Intercepts 


Navigation and Ancillary Information Facility 


¢ Determine the intersection of the apparent line of sight vector 
between Earth and Cassini with Saturn’s ring plane and determine 
the distance of this point from the center of Saturn. 
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Computing Ring Plane Intercepts-2 
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This simplified computation 
ignores the difference 
between the light time from 
Saturn to the Earth and the 
light time from the ring 
intercept point to the Earth. 


The position and 
orientation of Saturn could 
be re-computed using the 
light time from Earth to the 
intercept; the intercept 
could be re-computed until 
convergence is attained. 


Derived Quantities 


This computation is for the reception case, 
when radiation is received at the Earth ata 
given epoch “ET”. 
CALL SPKEZR to get light time corrected position of spacecraft as 
seen from Earth at time ET in J2000 reference frame SCVEC. 


CALL SPKEZR to get light time corrected position of center of Saturn 
at time ET as seen from Earth in J2000 frame SATCTR. 


CALL PXFORM to get rotation from Saturn body-fixed coordinates to 
J2000 at light time corrected epoch. The third column of this matrix 
gives the pole direction of Saturn in the J2000 frame SATPOL. 


CALL NVP2PL and use SATCTR and SATPOL to construct the ring 
plane RPLANE. 


CALL INRYPL to intersect the Earth-spacecraft vector SCVEC with 
the Saturn ring plane RPLANE to produce the intercept point X. 


CALL VSUB to get the position of the intercept with respect to Saturn 
XSAT (subtract SATCTR from X) and use VNORM to get the distance 


of XSAT from the center of Saturn. 
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Computing Ring Plane Intercepts-3 
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An 
alternate 
approach 
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Create a dynamic frame with one axis pointing from Earth to the 
light time corrected position of the Cassini orbiter. Use the CN 
correction for this position vector. (This gives us a frame in 
which the direction vector of interest is constant.) 


Temporarily change the radii of Saturn to make the polar axis 
length 1 cm and the equatorial radii 1.e6 km. This can be done 
either by editing the PCK or by calling BODVCD to fetch the 
original radii, then calling PDPOOL to set the kernel pool variable 
containing the radii to the new values. This flat ellipsoid will be 
used to represent the ring plane. 


Use SINCPT to find the intercept of the Earth-Cassini ray with the 
flat ellipsoid. Use the CN correction. SINCPT returns both the 
intercept in the IAU_SATURN frame and the Earth-intercept 
vector. Use VNORM to get the distance of the intercept from 
Saturn’s center. 


Restore the original radii of Saturn. If PDPOOL was used to 
update the radii in the kernel pool, use PDPOOL again to restore 


the radii fetched by BODVCD. 
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¢ Determine when the spacecraft will be occulted by 
an object (such as a natural satellite) as seen from 
an observer (such as Earth). 


Derived Quantities 


NAIF Computing Occultation Events 
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Find Occultation Ingress/Egress 


Navigation and Ancillary Information Facility 


¢ Select a start epoch, stop epoch and 
step size. 


— Start and stop epochs can bracket multiple 
occultation events 

— Step size should be smaller than the shortest 
occultation duration of interest, and smaller 
than the minimum interval between 
occultation events that are to be 
distinguished, but large enough to solve the 
problem with reasonable speed. 


¢ Insert search interval into a SPICE 
window. This is the “confinement 
window.” 


° CALL to find occultations, if any. 
The time intervals, within the confinement 
window, over which occultations occur will 
be returned in a SPICE window. 

— GFOCLT can treat targets as ellipsoids, DSK 
shapes, or points (but at least one must be an 
ellipsoid or DSK shape, and DSK shapes can 
be used only with point targets). 

— GFOCLT can search for different occultation 
or transit geometries: full, partial, annular, or 
“any.” 
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